Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add semantic conventions for process resource #635

Conversation

james-bebbington
Copy link
Member

Adds semantic conventions for process as a resource which represents a regular operating system process.

@james-bebbington james-bebbington changed the title Add semantic conventions for "process" resource Add semantic conventions for process resource Jun 5, 2020
@james-bebbington james-bebbington force-pushed the resource-semantic-conventions-process branch from 7761a88 to 1de8bf1 Compare June 8, 2020 03:49
@linux-foundation-easycla
Copy link

linux-foundation-easycla bot commented Jun 8, 2020

CLA Check
The committers are authorized under a signed CLA.

@carlosalberto carlosalberto self-requested a review June 8, 2020 14:25
@james-bebbington james-bebbington force-pushed the resource-semantic-conventions-process branch 3 times, most recently from 635ab7c to f8b55b0 Compare June 9, 2020 06:13
@arminru
Copy link
Member

arminru commented Jun 9, 2020

Please make sure to add an entry in the changelog:
https://github.com/open-telemetry/opentelemetry-specification/blob/master/CHANGELOG.md#unreleased

@james-bebbington james-bebbington force-pushed the resource-semantic-conventions-process branch 3 times, most recently from f679502 to 45f961f Compare June 9, 2020 23:31
CHANGELOG.md Outdated Show resolved Hide resolved
@carlosalberto carlosalberto added the area:semantic-conventions Related to semantic conventions label Jun 12, 2020
@james-bebbington james-bebbington force-pushed the resource-semantic-conventions-process branch from e2164c1 to 47c28ea Compare June 15, 2020 01:17
| process.executable_name | The name of the process executable. On Unix based systems, can be set to the `Name` in `proc/[pid]/status`. On Windows, can be set to the base name of `GetProcessImageFileNameW`. | `otelcol` | See below |
| process.executable_path | The full path to the process executable. On Unix based systems, can be set to the target of `proc/[pid]/exe`. On Windows, can be set to the result of `GetProcessImageFileNameW`. | `/usr/bin/cmd/otelcol` | See below |
| process.command | The command used to launch the process (i.e. the command name). On Unix based systems, can be set to the zeroth string in `proc/[pid]/cmdline`. On Windows, can be set to the first parameter extracted from `GetCommandLineW`. | `cmd/otelcol` | See below |
| process.commandline | The full command used to launch the process. This can be a nil- or space-delimited string. On Unix based systems, can be set to the full `proc/[pid]/cmdline` string. On Windows, can be set to the result of `GetCommandLineW`. | `cmd/otecol --config=config.yaml` | See below |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think using "nil" is clear here. Also, this is ambiguous. If I have only a single string with spaces but no nil, it is impossible to determine if I have some\ command\ with/spacesinpath and no arguments, or a GetCommandLineW-encoded command line.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is also concern around using two different data types to represent the same attribute value: #635 (comment). It might create additional complexity on back end systems to have to manage potentially different data types for the same attribute, though I'm not sure how much of a concern this would be? I guess parsing null-characters on the back end would likely be equivalently complex.

Note this isn't strictly ambiguous btw. If that was a command with no arguments, and you were looking at the Unix representation, it would have a null-character as the last character in the string. On Windows it would not. Admittedly that is not a great representational difference, and could be difficult to distinguish in some programming languages.

After thinking about this some more, I think I do prefer the list of strings approach, but I'm not sure I'm aware of all the pros/cons. For now I have changed it back to that, and updated the example for each OS accordingly. But for the record here's the three options considered and pros/cons:

  1. Join arguments with a string:
    Advantages: Most consistent representation across OSs.
    Disadvantages: Potentially lossy/non-trivial conversion on Unix - do we need to enquote parameters with spaces in them (and escape internal quotes), etc?
  2. Pass through string returned from OS as is (null-delimited on Unix):
    Advantages: No processing needed by code producing telemetry, can just provide what OS returns.
    Disadvantages: Back end needs to parse null-characters.
  3. Convert to list of strings (for Unix only):
    Advantages: Clean ("properly typed") representation.
    Disadvantages: Inconsistent data type for the same attribute between OSs, and back end needs to handle this differently.

FYI @arminru note I've reverted the changes based on your last comment since you approved. Please take another look.

@igorpeshansky you may also be interested.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Interestingly ps on Mac and Linux doesn't appear to apply any quoting so if there are spaces or quotes in in your argument (e.g. app --set "foo bar") ps doesn't appear to quote them. We could quote them (https://godoc.org/github.com/gonuts/go-shellquote#Join [1]). I can't think of any downsides in particular when it comes to filtering on quoted values. I think in most cases you're not going to be doing filtering on values that have quotes in them or other escaped characters. I imagine the common case is you're searching for commands that have basic things like "repl-factor" or some such in it.

[1] Not endorsing it, just searched for a shell escape library in go.

@james-bebbington james-bebbington force-pushed the resource-semantic-conventions-process branch from 47c28ea to f11188f Compare June 16, 2020 02:28
Copy link
Contributor

@MrAlias MrAlias left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In favor of the addition. Only questions are around specific naming, i.e. just bikeshedding.

specification/resource/semantic_conventions/README.md Outdated Show resolved Hide resolved
| process.executable_name | The name of the process executable. On Unix based systems, can be set to the `Name` in `proc/[pid]/status`. On Windows, can be set to the base name of `GetProcessImageFileNameW`. | `otelcol` | See below |
| process.executable_path | The full path to the process executable. On Unix based systems, can be set to the target of `proc/[pid]/exe`. On Windows, can be set to the result of `GetProcessImageFileNameW`. | `/usr/bin/cmd/otelcol` | See below |
| process.command | The command used to launch the process (i.e. the command name). On Unix based systems, can be set to the zeroth string in `proc/[pid]/cmdline`. On Windows, can be set to the first parameter extracted from `GetCommandLineW`. | `cmd/otelcol` | See below |
| process.commandline | The full command used to launch the process. The value can be either a list of strings representing the ordered list of arguments, or a single string representing the full command. On Unix based systems, can be set to the list of null-delimited strings extracted from `proc/[pid]/cmdline`. On Windows, can be set to the result of `GetCommandLineW`. | Unix: `[ cmd/otecol, --config=config.yaml ]`, Windows: `cmd/otecol --config=config.yaml` | See below |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I usually see commandline as two words. Do we want to build naming hierarchy here as well? Or, just insert a separator?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changed this to process.command_line for now. I'm not sure if process.command.name would be a reasonable name for the "command"

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SGTM 👍

@james-bebbington james-bebbington force-pushed the resource-semantic-conventions-process branch from f11188f to 66a9aa6 Compare June 18, 2020 05:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area:semantic-conventions Related to semantic conventions spec:resource Related to the specification/resource directory
Projects
None yet
Development

Successfully merging this pull request may close these issues.

8 participants